Parent PRD

#4144

Summary

Foundation layer for mixed OAuth2 scope support. Renames PDPBackend.PresentationDefinitions() to FindCredentialProfile() and enriches its return type to include the credential profile scope, its policy, and any remaining ("other") scopes. Extends the policy JSON format with a scope_policy field and adds a policy.authzen.endpoint CLI flag validated at startup.

What changed

Policy interface (policy/interface.go, policy/local.go):

• Method renamed PresentationDefinitions → FindCredentialProfile, returning *CredentialProfileMatch (scope, WalletOwnerMapping, scope policy, other scopes) instead of just pe.WalletOwnerMapping.
• Multi-scope parsing via strings.Fields (tolerant of tabs, newlines, consecutive spaces).
• New errors: ErrAmbiguousScope (multiple profile scopes in one request), distinct from ErrNotFound.

Policy JSON format (policy/local.go, policy/test/scope_policy/):

• Added scope_policy field per credential profile: "profile-only" (default), "passthrough", or "dynamic".
• Existing policy files without scope_policy continue to work (defaults to profile-only).
• Internal credentialProfileConfig replaces the map-based validatingWalletOwnerMapping with an explicit struct (organization/user fields + scope_policy).
• PD schema validation preserved via validatingPresentationDefinition — moved from mapping-level to per-PD level.

Config & validation (policy/config.go, policy/cmd.go, policy/local.go):

• New policy.authzen.endpoint CLI flag.
• Startup fails when any credential profile uses dynamic without an AuthZen endpoint configured.
• passthrough and profile-only continue to work without an endpoint.

Callers updated (auth/api/iam/):

• validation.go and api.go updated for the new return type, with ErrAmbiguousScope mapped to invalid_scope.
• Mock regenerated; existing test expectations updated to use *CredentialProfileMatch.

How to review

Start with policy/interface.go — understand the new types (CredentialProfileMatch, ScopePolicy) and the renamed interface method.

Then policy/local.go — the core logic:

• FindCredentialProfile (scope parsing + classification)
• credentialProfileConfig.UnmarshalJSON (JSON format handling)
• Configure (startup validation for AuthZen endpoint)

Tests to focus on (policy/local_test.go):

• TestLocalPDP_FindCredentialProfile — multi-scope parsing edge cases (consecutive whitespace, empty strings, multiple profile scopes, zero profile scopes)
• TestLocalPDP_ScopePolicyConfig — JSON parsing, invalid value rejection
• TestLocalPDP_Configure — startup validation behavior

Callers (auth/api/iam/) are mechanical updates — they extract .WalletOwnerMapping from the result to preserve existing behavior.

Deviations from spec

• credentialProfileConfig uses an explicit struct with Organization/User fields, not the map-based approach suggested in the spec. This avoided custom JSON parsing of the scope_policy field while preserving the existing flat JSON format. PD validation moved to per-PD level (still uses the v2 schema).
• Added ErrAmbiguousScope as a distinct error (not in spec). Wrapping ErrNotFound for "too many profile scopes" was semantically wrong.
• Added nil-check that credential profile JSON must define at least one of organization / user — catches typos like organisations that standard struct unmarshaling would silently accept.
• Used strings.Fields instead of strings.Split — handles tabs, newlines, and consecutive spaces robustly.

Dependencies

None — this is the foundation PR. Subsequent PRs #4177–#4180 build on this interface.

Design context

• PRD: Support mixed OAuth2 scopes with configurable scope policy #4144 (mixed OAuth2 scopes with configurable scope policy)
• Scope policy modes discussion: passthrough mode was added in-scope after initial PR split (see PRD comment 4235711103)
• Related issue: Consider circuit breaker for AuthZen PDP client #4175 (circuit breaker for AuthZen client — future enhancement)

Acceptance Criteria

• FindCredentialProfile() accepts space-delimited multi-scope strings (uses strings.Fields for robust whitespace handling)
• Returns exactly one credential profile scope or errors (ErrNotFound for zero, ErrAmbiguousScope for multiple)
• scope_policy field parsed from policy config (defaults to "profile-only")
• Invalid scope_policy values rejected at load time
• Credential profile must define at least one of organization or user
• policy.authzen.endpoint config field and CLI flag added
• Startup fails when dynamic scope policy is used without AuthZen endpoint
• passthrough and profile-only work without AuthZen endpoint
• All existing tests pass (callers and mocks updated for new interface)
• New unit tests for scope parsing, config loading, and startup validation
• PD validation preserved via validatingPresentationDefinition (validates against v2 JSON schema)

type PDPBackend interface {
    FindCredentialProfile(ctx context.Context, scope string) (*CredentialProfileMatch, error)
}

type CredentialProfileMatch struct {
    CredentialProfileScope string
    WalletOwnerMapping     pe.WalletOwnerMapping
    ScopePolicy            ScopePolicy
    OtherScopes            []string
}

{
  "urn:nuts:medication-overview": {
    "organization": { /* PD */ },
    "scope_policy": "profile-only"
  }
}